/*
 * CX3K Scheduler
 * UMBC CMSC 345, FA2009
 * 
 * Group 6 (cmsc345group6@googlegroups.com)
 * Charles Crookes
 * Christopher Hayes
 * Christopher Thierer
 * Kyle Willett
 * 
 * Copyright 2009 by above individuals
 * Distributed under GNU General Public License, v2
 * Warranty information can be found at /warranty.txt
 * The GNU is available at /gpl-v2.txt
 */

package cx3k.dataaccess;
import java.util.Collection;
import java.util.Map;

import cx3k.dataaccess.exceptions.DataAccessException;
import cx3k.scheduler.objects.Course;
import cx3k.scheduler.objects.Major;
import cx3k.scheduler.objects.Minor;
import cx3k.scheduler.objects.Profile;
import cx3k.scheduler.objects.Schedule;
import cx3k.scheduler.objects.Semester;

/**
 * Provides access for the Scheduler system to the necessary persistent data 
 * components.  The service is designed to handle two types of data:
 * <ul>
 * <li>
 * 		<i>Profiles</i>:  Profile objects contain information about
 * 		the student (name, majors, minors, etc.), as well as courses that
 * 		the student has already completed.
 * </li>
 * <li>
 * 		<i>Schedules</i>: Schedule objects define a schedule for an entire
 * 		academic career, including all semesters.  
 * </li>
 * </ul>
 * 
 * @author Chris Thierer
 *
 */
public interface DataAccessService {
	
	/**
	 * Remove the profile mapped to the parameter ID from storage.  This
	 * procedure cannot be undone.
	 * 
	 * @param 	profileId The ID of the profile object to be deleted from storage.
	 * @throws 	DataAccessException Thrown if the persistent storage cannot 
	 * 			be accessed.
	 */
	public void deleteProfile(int profileId)
	throws DataAccessException;
	
	/**
	 * Remove the profile corresponding to the parameter object from storage.  
	 * This procedure cannot be undone.
	 * 
	 * @param delete The Profile object to be deleted from storage.
	 * @throws	DataAccessException Thrown if the persistent storage cannot
	 * 			be accessed.
	 */
	public void deleteProfile(Profile delete)
	throws DataAccessException;
	
	/**
	 * Remove the schedule mapped to the parameter ID from storage.  This
	 * procedure cannot be undone.
	 * 
	 * @param 	scheduleId The ID of the schedule object to be deleted from storage.
	 * @throws 	DataAccessException Thrown if the persistent storage cannot 
	 * 			be accessed.
	 */
	public void deleteSchedule(int scheduleId)
	throws DataAccessException;
	
	/**
	 * Remove the schedule corresponding to the parameter object from storage.  
	 * This procedure cannot be undone.
	 * 
	 * @param delete The Schedule object to be deleted from storage.
	 * @throws	DataAccessException Thrown if the persistent storage cannot
	 * 			be accessed.
	 */	
	public void deleteSchedule(Schedule schedule) 
	throws DataAccessException;
	
	/**
	 * Load all courses from storage, mapped to their Course ID.  Courses
	 * cannot be changed via the Data Access Service.
	 * 
	 * @return	A Map where the key values are Course IDs, and the mapped 
	 * 			values are instances of Courses retrieved from persistent 
	 * 			storage.
	 */
	public Map<Integer, Course> getAllCourses();
	
	/**
	 * Load all majors from storage, mapped to their Major ID.  Majors 
	 * cannot be changed via the Data Access Service.
	 * 
	 * @return 	A Map where the key values are Major IDs, and the mapped 
	 * 			values are instances of Majors retrieved from persistent 
	 * 			storage.
	 */
	public Map<Integer, Major> getAllMajors();
	
	/**
	 * Load all minors from storage, mapped to their Minor ID.  Minors 
	 * cannot be changed via the Data Access Service.
	 * 
	 * @return	A Map where the key values are Minor IDs, and the mapped 
	 * 			values are instances of Minors retrieved from persistent 
	 * 			storage. 
	 */
	public Map<Integer, Minor> getAllMinors();
	
	/**
	 * Load a profile, specified by the profile ID passed in.  If the profile
	 * ID does not map to an actual profile, then null is returned.  The 
	 * Profile object returned will be initialized to match the data contained
	 * in the persistent storage.  
	 * 
	 * @param	profileId The unique ID corresponding to the profile to be loaded.
	 * @return 	A profile object that is initialized to match the information
	 * 			contained within the storage; null if the ID value did not map
	 * 			to a record.
	 * @throws 	DataAccessException	Thrown if the persistent storage cannot
	 * 			be accessed.
	 */
	public Profile getProfile(int profileId)
	throws DataAccessException;
	
	/**
	 * Load all profiles from persistent storage.  The Profile objects that 
	 * are returned will be initialized to match the data contained in 
	 * the storage.
	 * 
	 * @return	A List of all Profiles from storage, an empty set of there 
	 * 			are no profiles, or null in any other case.
	 * @throws 	DataAccessException Thrown if the persistent storage cannot be 
	 * 			accessed.
	 */
	public Map<Integer, Profile> getProfiles()
	throws DataAccessException;
	
	/**
	 * Load a schedule, specified by the schedule ID passed in.  If the schedule
	 * ID does not map to an actual schedule, then null is returned.  The 
	 * Schedule object returned will be initialized to match the data contained
	 * in the persistent storage.  
	 * 
	 * @param	scheduleId The unique ID corresponding to the schedule to be loaded.
	 * @return 	A schedule object that is initialized to match the information
	 * 			contained within the storage; null if the ID value did not map
	 * 			to a record.
	 * @throws 	DataAccessException	Thrown if the persistent storage cannot
	 * 			be accessed.
	 */
	public Schedule getSchedule(int scheduleId)
	throws DataAccessException;
	
	/**
	 * Load all schedules from persistent storage.  The Schedule objects that 
	 * are returned will be initialized to match the data contained in 
	 * the storage.
	 * 
	 * @return	A List of all Schedules from storage, an empty set of there 
	 * 			are no profiles, or null in any other case.
	 * @throws 	DataAccessException Thrown if the persistent storage cannot be 
	 * 			accessed.
	 */
	public Map<Integer, Schedule> getSchedules() 
	throws DataAccessException;
	
	/**
	 * Load all semesters from storage, mapped to their Semester ID.  Semesters
	 * cannot be changed via the Data Access Service.
	 * 
	 * @return	A Map where the key values are Semester IDs, and the mapped 
	 * 			values are instances of Semester retrieved from persistent 
	 * 			storage.
	 */
	public Map<Integer, Semester> getAllSemesters();
	
	/**
	 * Save the profile object passed in to persistent storage.  If the 
	 * Profile parameter matches an existing profile in storage, then the 
	 * profile parameter will override the existing information in storage;
	 * otherwise, the new profile will be added to the storage.
	 *  
	 * @param 	profile The Profile to be committed to storage.
	 * @throws 	DataAccessException Thrown if the persistent storage cannot
	 * 			be accessed.
	 */
	public void saveProfile(Profile profile)
	throws DataAccessException;
	
	/**
	 * Save all profile objects in the set passed in to persistent storage.  For
	 * each Profile, if it already exists, then the record will be updated;
	 * otherwise, the Profile will be added to the storage.  
	 * 
	 * @param	profiles The List of Profiles to be committed to storage.
	 * @throws 	DataAccessException Thrown if the persistent storage cannot
	 * 			be accessed.
	 */
	public void saveProfiles(Collection<Profile> profiles)
	throws DataAccessException;
	
	/**
	 * Save the schedule object passed in to persistent storage.  If the 
	 * Schedule parameter matches an existing schedule in storage, then the 
	 * schedule parameter will override the existing information in storage;
	 * otherwise, the new schedule will be added to the storage.
	 *  
	 * @param 	schedule The Schedule to be committed to storage.
	 * @throws 	DataAccessException Thrown if the persistent storage cannot
	 * 			be accessed.
	 */
	public void saveSchedule(Schedule schedule)
	throws DataAccessException;
	
	/**
	 * Save all schedule objects in the set passed in to persistent storage.  For
	 * each Schedule, if it already exists, then the record will be updated;
	 * otherwise, the Schedule will be added to the storage.  
	 * 
	 * @param	schedules The List of Schedules to be committed to storage.
	 * @throws 	DataAccessException Thrown if the persistent storage cannot
	 * 			be accessed.
	 */
	public void saveSchedules(Collection<Schedule> schedules) 
	throws DataAccessException;
	
	/**
	 * Specify the location of the persistent storage for profiles.  This
	 * could be a file location, a URL, a SQL connection, etc., depending on 
	 * how profiles are stored. Implementation of this method is optional.  
	 * 
	 * @param	location Necessary parameters to connect or load the persistent
	 * 			storage for profiles.
	 */
	public void setProfileLocation(String location);
	
	/**
	 * Specify the location of the persistent storage for schedules.  This
	 * could be a file location, a URL, a SQL connection, etc., depending on 
	 * how schedules are stored. Implementation of this method is optional. 
	 *  
	 * @param	location Necessary parameters to connect or load the persistent
	 * 			storage for schedules.
	 */
	public void setScheduleLocation(String location);
	
}
